<ui:composition template="/WEB-INF/templates/showcase.xhtml"
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:o="http://omnifaces.org/ui"
>
	<ui:define name="description">
		<p>
			This filter will apply GZIP compression on responses whenever applicable. GZIP will greatly reduce the response size
			when applied on character based responses like HTML, CSS and JS, on average it can save up to ~70% of bandwidth.
			While GZIP is normally to be configured in the servletcontainer (e.g. <code>&lt;Context compression="on"&gt;</code>
			in Tomcat, or <code>&lt;property name="compression" value="on"&gt;</code> in Glassfish), this filter allows a
			servletcontainer independent way of configuring GZIP compression and also allows enabling GZIP compression anyway
			on 3rd party hosts where you have no control over servletcontainer configuration.
		</p>
		
		<h3>Installation</h3>
		<p>
			To get it to run, map this filter on the desired <code>&lt;url-pattern&gt;</code> or maybe even on the
			<code>&lt;servlet-name&gt;</code> of the <code>FacesServlet</code>. A <code>Filter</code> is by default dispatched
			on <code>REQUEST</code> only, you might want to explicitly add the <code>ERROR</code> dispatcher to get it to run
			on error pages as well.
		</p>
		<pre class="prettyprint"><code class="lang-xml">
&lt;filter&gt;
    &lt;filter-name&gt;gzipResponseFilter&lt;/filter-name&gt;
    &lt;filter-class&gt;org.omnifaces.filter.GzipResponseFilter&lt;/filter-class&gt;
&lt;/filter&gt;
&lt;filter-mapping&gt;
    &lt;filter-name&gt;gzipResponseFilter&lt;/filter-name&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
    &lt;dispatcher&gt;REQUEST&lt;/dispatcher&gt;
    &lt;dispatcher&gt;ERROR&lt;/dispatcher&gt;
&lt;/filter-mapping&gt;
		</code></pre>

		<h3>Configuration (optional)</h3>
		<p>
			This filter supports two initialization parameters which needs to be placed in <code>&lt;filter&gt;</code> element
			as follows:
		</p>
		<pre class="prettyprint"><code class="lang-xml">
&lt;init-param&gt;
    &lt;description&gt;
        The threshold size in bytes. Must be a number between 0 and 9999. Defaults to 500.
    &lt;/description&gt;
    &lt;param-name&gt;threshold&lt;/param-name&gt;
    &lt;param-value&gt;500&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;init-param&gt;
    &lt;description&gt;
        The mimetypes which needs to be compressed. Must be a commaseparated string. Defaults to the below values.
    &lt;/description&gt;
    &lt;param-name&gt;mimetypes&lt;/param-name&gt;
    &lt;param-value&gt;
        text/plain, text/html, text/xml, text/css, text/javascript, text/csv, text/rtf,
        application/xml, application/xhtml+xml, application/javascript, application/json
    &lt;/param-value&gt;
&lt;/init-param&gt;
		</code></pre>
		<p>
			The default <code>threshold</code> is thus 500 bytes. This means that when the response is not larger than 500 bytes,
			then it will not be compressed with GZIP. Only when it's larger than 500 bytes, then it will be compressed. A
			threshold of between 150 and 1000 bytes is recommended due to overhead and latency of compression/decompression.
			The value must be a number between 0 and 9999. A value larger than 2000 is not recommended.
		</p>
		<p>
			The <code>mimetypes</code> represents a commaseparated string of mime types which needs to be compressed. It's
			exactly that value which appears in the <code>Content-Type</code> header of the response. The in the above example
			mentioned mime types are already the default values. Note that GZIP does not have any benefit when applied on
			binary mimetypes like images, office documents, PDF files, etcetera. So setting it for them is not recommended.
		</p>

		<h3>Demo</h3>
		<p>
			The <code>GzipResponseFilter</code> is also 
			<a href="http://code.google.com/p/omnifaces-showcase/source/browse/WebContent/WEB-INF/web.xml">configured</a>
			on this showcase application. You can see it by responses being gzipped and by the presence of the filter
			in stacktraces of showcase pages demonstrating some exceptions.
		</p>			
	</ui:define>		
</ui:composition>